home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BBS Toolkit
/
BBS Toolkit.iso
/
rbbs_pc
/
rbbsdocs.zip
/
RBBSDOCS.7
< prev
next >
Wrap
Text File
|
1990-11-05
|
89KB
|
1,892 lines
PLANNING YOUR USER INTERFACE 7-1
7. PLANNING YOUR USER INTERFACE
--------------------------------
RBBS-PC provides each SysOp the maximum control over what is presented to
callers. There are three areas of control:
- The menus presented to novice callers.
- What is included in the prompt all users get.
- What symbol invokes a particular function.
7.1 Menus Shown to Callers
--------------------------
The menus in RBBS-PC are external text files that are presented to novice
users. RBBS-PC simply displays what is in these files to the callers.
Therefore, SysOps are free to change the text in these files to whatever
they desire. Simply edit the files. However, be sure to use an editor
that produces only ASCII text files with no special embedded characters.
Most word processing editors are not suitable because they insert special
symbols in the file meaningful only to it. Menus can also contain graphics
and color (see section 6.3).
7.2 Subsystem Prompts Shown to Callers
--------------------------------------
RBBS-PC has several configuration options which allow each SysOp to select
the prompts that are presented to callers. They are:
- Whether the section name is displayed.
- Whether the letters of the available commands are shown.
The commands in RBBS-PC are divided into four sections: MAIN, FILE,
UTILITY and LIBRARY. If RBBS-PC is configured to display the section name,
the command prompt will read "<section> command", otherwise "Your command".
The section name is shown by default.
RBBS-PC normally prompts a caller with the commands the caller has
sufficient security to invoke. Each command is a single letter and is
shown separated from the others by a comma. The command letters can be
suppressed in the prompt. By leaving them on a SysOp provides each caller
with a terse but helpful reminder of what commands are available to them.
7.3 Commands Available to Callers
---------------------------------
All primary commands in RBBS-PC are invoked by single letter commands. An
attempt is made to associate the command with the first letter in a word
which describes the function, so that the command letter appears to be a
short abbreviation for the longer word. The command to invoke reading
messages is R. The default symbols that would be shown in the command line
for each section are:
sect |? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y 1 2 3 4 5 6 7
-----|-------------------------------------------------------------------
MAIN |? @ A B C D E F H I J K O P Q R S T V W X 1 2 3 4 5 6 7
|
FILE |? D G H L N P Q S U V X
|
UTIL |? B C E F G H L M P Q R S T U X
|
LIB |? A C D G H L Q S V X
|
GLBL |? H Q X
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-2
Four commands, ? H Q and X, have the same meaning in every section and are
known as "global." The other commands all have unique function specific
for the section within which they are invoked. For example, S stands for
S)can messages in MAIN, S)earch in FILE and LIBRARY, and S)tatistics in
UTIL. Symbols 1-7 are used for SysOp functions.
RBBS-PC allows the SysOp to substitute any symbol for any command. Y)ell
may be substituted for O)perator page, or Y)our mail for P)ersonal mail.
If a blank is substituted, the command is removed from the list and is no
longer available.
7.4 RBBS-PC's "Wrap-around" Command Search
------------------------------------------
There is an option in CONFIG which gives the SysOp unusual flexibility in
configuring the user interface. A caller is always "in" a section.
RBBS-PC considers the user's current section when acting on commands. The
"wrap around" option allows RBBS-PC to look further for a command when it
is not found in the section the caller is in. If a SysOp substitutes a
blank for the V>iew conference command in the main section (as mentioned in
section 7.3) and a user enters the V command from the main section, the
V)iew archive file command would be what the caller would have invoked.
The fundamental idea is to look further in other sections, where the search
order is circular, starting at the current section, and proceeding in the
following order:
-MAIN->FILE->UTIL->LIBRARY->GLOBAL->SYSOP-
| |
-------------------<----------------------
If wrap-around is used, RBBS-PC will search ALL sections, in order, to find
a valid command that matches the user's input. Even if wrap-around is not
used, GLOBAL and SYSOP commands are processed globally.
The important feature that wrap-around supports is that a command with a
unique letter works in all sections. Thus W)ho will work everywhere if
wrap-around is enabled. If every RBBS-PC command is given a unique symbol,
all commands become global and there is no effective difference between
sections. This allows SysOps to make commands available on a single level
and makes it unnecessary to "go" to a section before using a command in
that section.
7.5 How to Have a Single Universal Command Line
------------------------------------------------
The command structure within RBBS-PC can be made "flatter" without making
it absolutely flat. Suppose, for example, that a SysOp wants callers to be
able to do all file functions without going to a files section. In effect,
the file functions are available in the main section, or the file section
is merged into the main section. To do this, the SysOp must eliminate the
overlap in command letters between the two sections.
The main section and the file section share the letters D, P, S, and V. V
is used to "view" a conference in the main section and "view" what is
contained in an archived file. D is difficult because both D)oors and
D)ownload are entrenched and natural options. One could leave D for the
most frequently used function, say download, then use a special but
arbitrary symbol like # for doors. Similarly, V could be left for viewing
conference mail in the main section and a special but arbitrary symbol like
& for viewing archived files in the file section. S)earch for substrings
PLANNING YOUR USER INTERFACE 7-3
could be replaced by F)ind since F for going to F)iles is no longer needed.
This could be accomplished by disabling F)iles and substituting F for S in
the files commands.
P is used for personal mail in the main section as well as personal files
in the file section. Leaving P in the main section for personal mail and
selecting the symbol M for personal mail in the file section would have the
least impact on callers.
U is used for upload. Since Quit may be used to go to UTIL, we can disable
U in the main menu. We can use W for W)rite user preferences and F to find
who else is on (since the F for FILES section is no longer needed). We
could then revise the main menu to read:
R B B S M A I N M E N U
~~~~~~~~~~~~~~~~~~~~~~~~~~~
[A]nswer survey [H]elp (or ?) [P]ersonal mail [U]pload a file
[B]ulletins [I]nitial welcome [$]Personal files [V]iew conference mail
[C]omments [J]oin conference [Q]uit [&]View ARC files
[#]DOORS [K]ill message [R]ead messsages [W]rite user pref
[D]ownload [L]ist files [S]can messages [X]pert on/off
[E]nter msg [N]ew files [T]opic msg scan [Z]ippy search
[F]ind who's on [O]perator page [@]Library
[G]oodbye
Obviously the limitations of using a single section (as the more primitive
bulletin board systems do) means that the number of commands must be
restricted to either
- 26 (letters in the alphabet), or
- 36 (letters in the alphabet plus the numbers 0 through 9), or
- full "words".
With this artificial limitation of a single section, commands become
limited in number, cryptic, or both. If the even more clumsy use of full
"words" is chosen, the system must slow down as it can no longer act
immediately upon seeing the first character of a command as RBBS-PC does.
However, assuming that someone would actually want to configure RBBS-PC to
be "flat" (i.e. have a single command line), let us continue. In order not
to confuse the caller by being in a section and seeing only some of the
commands we want him to use, the SysOp could elect not to show the section
in the prompt (CONFIG parameter 37) and not to show the commands (CONFIG
parameter 38). Callers would see simply "Your command?" as the prompt.
This makes the expert mode quite terse, but that simply means users would
spend more time in novice mode before using expert.
Now suppose that only a single command line was desired and that the
commands from the "Utilities" menu commands were to be added to the above.
The "global" H, ?, Q, and X commands already are in the single command
line.
M for message margin can remain unchanged since it is unique to the
Utilities subsystem.
In order to accommodate the redundancy of letters that exist by including
the Utilities subsystem's commands, the W command for the main message
subsystem can be re-enabled and the remote SysOps commands be eliminated in
order to re-use the numbers. The Utilities subsystem commands B, C, F, G,
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-4
L, R, and S could then be replaced by the numbers 1 through 9. The
Utilities subsystem commands T, U, E, and P could be replaced by the
commands <, >, \, and !, respectively.
This final menu of all RBBS-PC commands could be re-written without any
apparent sub-sections as follows and the screen that the would appear to
the "novice" users as:
R B B S C O M M A N D S
~~~~~~~~~~~~~~~~~~~~~~~~
[A]nswer survey [O]perator page [1] Change Baud Rate 300-->450
[B]ulletins [$]Personal files [2] Display time of day
[C]omments [P]ersonal mail [3] Set file transfer protocol
[#]DOORS [Q]uit [4] Set type of graphics mode
[D]ownload [R]ead messages [5] Set page length
[E]nter msg [S]can messages [8] Review callers preferences
[G]oodbye [T]opic msg scan [9] Display system statistics
[H]elp (or ?) [U]pload a file [<] Toggle users options on/off
[I]nitial welcome [V]iew conference mail [>] Show the log of callers
[J]oin conference [&]View ARC files [@] Library
[K]ill message [W]ho's on other nodes [\] Change echo selection
[L]ist files [X]pert on/off [!] Change password
[M]argin set [Z]ippy search
[N]ew files
Your command?
7.6 RBBS-PC'S Programmable User Interface (PUI)
-----------------------------------------------
The programmable user interface (PUI, pronounced "pee you eye") lets the
SysOp take TOTAL CONTROL over what the caller is presented with, including:
- the novice menu
- the prompt line
- the organization of commands into groups (sections)
- the flow between sections
- unlimited levels of nested menus.
This allows the RBBS-PC interface that the caller sees to take on any
appearance desired by the SysOp. In effect, the SysOp is limited only by
the intrinsic functions of RBBS-PC that have been programmed into RBBS-PC
source code. These functions can be assigned any command letter desired in
CONFIG. PUI lets the SysOp completely control how these commands are
presented to the user - allowing RBBS-PC to "emulate" virtually any other
host communications environment that the SysOp's callers may be familiar
with.
If no PUI is provided, RBBS-PC defaults to dividing the commands into a
MAIN, FILES, UTILITIES, and LIBRARY section.
RBBS-PC's PUI gives each SysOp the flexibility to tailor RBBS-PC to meet
special needs. In effect, RBBS-PC's PUI allows the SysOp to adjust RBBS-PC
to what the SysOp wants, rather than forcing the SysOp and his callers to
conform to RBBS-PC.
However, unlike RBBS-PC, the PUI does not adjust the prompt to show only
the commands that the user has sufficient security to do. And, of course,
PUI takes much more time to design and implement.
PLANNING YOUR USER INTERFACE 7-5
When the SysOp takes control of what the user is presented by using the
PUI, RBBS-PC does what the SysOp has explicitly set up -- and nothing else!
For example, RBBS-PC's "global" commands, like help and the expert toggle,
are no longer automatically available everywhere. They are available only
where the SysOp has indicated via the PUI.
RBBS-PC's default user interface has evolved over the years to represent
what the callers found useful (not the SysOps!). A great deal of time and
thought went into RBBS-PC's default user interface, and it is easy to
overlook important things when a SysOp goes about setting up his or her
own. When using the PUI assume that a new user interface will take time to
both develop and refine (based on your callers feedback). Designing and
implementing a PUI is not a simple undertaking as it is a total replacement
for RBBS-PC's standard user interface.
7.6.1 An Example Using PUI
--------------------------
The main menu in RBBS-PC can represent a bewildering variety of commands,
especially to a new user. Studies show that human beings can effectively
deal with at most 7 choices at one time, whereas RBBS-PC has 10 more than
that in its main section. To help people in this situation, the different
choices in RBBS-PC are grouped into related commands, but the choices can
still be overwhelming. Some SysOps have tried to simplify the main menu by
breaking it up into more sections. The most tempting group of commands to
spin off are the message commands. Suppose the main menu is to be
simplified to look like:
<F>iles
<M>ail
<U>ser preferences
<G>oodbye
The <M>ail command puts the caller in a section where commands related to
messages become available in yet another menu, such as J)oin and E)nter.
PUI is required because the commands are grouped into different sections.
While the default menu of RBBS-PC could be edited to say this, the
underlying commands would not be grouped as desired.
7.6.2 How to Implement PUI
--------------------------
First, plan carefully on paper exactly what you want the caller to see and
what happens with each command. Consider also, if you have a submenu, how
users are to get out of it.
Each menu or section of PUI is controlled by a file whose extension is
"PUI". The PUI is installed by putting a "main" PUI file whose name is
specified in CONFIG. The default is "MAIN.PUI". Each sub-board in RBBS-PC
can have a different PUI system if desired. A PUI file consists of exactly
10 lines, and the format is:
LINE CONTENTS
1 name of novice menu
2 prompt to display
3 valid commands, corresponding RBBS-PC commands
4 which valid commands are menus
5 names of PUIs that are menus
6 letter of quit command
7 prompt for quit command
8 valid sub-commands of quit command
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-6
9 which quit commands are PUIs
10 names of menu PUIs in quit command
The text in the lines should NOT be enclosed in quotes, except possibly the
two parts of line 3.
The novice menu is just a text file displayed to novices, just like the
default menus (MENU1, MENU2, etc.). The name can include a drive or path
as well as an extension. The menu PUIs in lines 5 and 10 must be stored in
the same drive/path as that in line 1.
The prompt to display is what all callers see when asked for a choice,
including experts. Normally this includes a brief listing of the commands
available along with a request for a command. This prompt is NOT
dynamically adjusted to reflect the security level of the caller, unlike
the default prompt in RBBS-PC, which removes commands the caller cannot
execute.
Each PUI defines a "section" of RBBS-PC (just like RBBS-PC has main, file,
library, and utility sections). The valid commands are the symbols for the
acceptable commands in this PUI section. They must be upper case only.
The first part is the names of the commands that the caller must give.
Each symbol must be mapped to a corresponding internal symbol name in
RBBS-PC which is set in CONFIG. This way the same letter in a given menu
can be used for different commands in RBBS-PC, just as "S" stands for S)can
messages in the main section and S)ubstring search in the files section.
Since the default underlying RBBS-PC commands use the same letter in
different menus, you should first reconfigure RBBS-PC to assign each
RBBS-PC command a different underlying symbol. Then in the PUI file map
the letter you want the caller to use to that underlying symbol. Be sure
in configuration NOT to limit commands to the current section -- you must
let RBBS-PC search in other sections for underlying commands when it does
not find it in the current section.
In addition to the normal commands available in RBBS-PC, the SysOp can
include new commands which invoke other menus. These must be symbols in
the list of valid commands.
If a valid menu choice is picked, there must be a PUI file for that choice.
Line 5 tells what prefix the PUI file has. Each PUI name must consist of
exactly 7 characters. The PUI name can be shorter than 7 letters, but in
the list you must blank fill out to 7 positions to the right. The first 7
characters are for the first valid menu command, the second 7 characters
are for the second valid menu command, etc. RBBS-PC will automatically
append the extension "PUI" to this file name. Note that all PUI files must
be in the same drive/path as the novice menu in line 1.
The last 5 lines in the PUI file concern how control goes from one PUI to
another. The PUI processing supports a "quit to" command in which the
caller can jump to other menus - which one is specified in the subcommands
to the quit command (just like RBBS-PC's "quit" to command).
Line 6 is the symbol (in the valid commands) which is the quit-to command.
It must be a single capital letter.
Line 7 is the prompt for the quit-to command, to be presented to callers
after they select the quit-to command (type ahead is supported).
PLANNING YOUR USER INTERFACE 7-7
Line 8 is the list of the valid sub-commands of the quit-to command. Each
command must be a capital letter.
Line 9 tells which of the valid subcommands are PUI commands. If a
sub-command is valid but not a PUI command, control will be passed to
RBBS-PC to process the quit-to command. For example, Quit-to S)ystem for
hanging up would have to be processed this way.
Line 10 tells what are the names of the PUI files for each PUI command in
line 9. The format of the PUI names is exactly the same as in line 5 -- 7
characters blank filled to the right if shorter.
The following file MAIN.PUI installs the example that was discussed in the
previous section:
MMENU
Enter choice: <F,M,U,G>
FGMU," G "
FMU
FMENU MAILM UMENU
<5 blank lines follow>
The name of the menu to be displayed initially is MMENU. The prompt users
will see is "Enter choice: <F,M,U,G>?" (RBBS-PC adds the trailing "?" for
prompts). The four valid commands are F, G, M, and U. Three of these
commands invoke other menus (F, M, and U), and G is a non-menu command,
i.e. one of the base RBBS-PC functions. The PUI file name for "F" is
FMENU.PUI, MAILM.PUI for "M", and UMENU.PUI for "U". Each of these PUI
files gives the same type of information as the main PUI. For example,
MAILM.PUI might contain
MAILM.MNU
Enter choice: <E,J,P,Q,R,S,T>
EJPQRST,EJPQRST
Q
MAIN
<5 blank lines follow>
The novice menu for the mail section is in file MAILM.MNU. This file might
contain the following text:
M A I L S U B S Y S T E M
~~~~~~~~~~~~~~~~~~~~~~~~~~~
E)nter a message
J)oin a new message base
P)ersonal mail (review)
Q)uit to main section
R)ead messages
S)can msg headers
T)opic msg scan
The prompt will appear immediately below this line unless an extra blank
line is included in the menu file. There is only one menu command: Q for
getting back to the main menu.
The PUI system can also be used to emulate the default RBBS-PC commands
with 4 sections. Four sample files are provided for accomplishing this:
XMAIN.PUI, XFILE.PUI, XUTIL.PUI, and XLIBR.PUI. For novice menus, each
uses the standard default menu that comes with RBBS-PC. These require
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-8
RBBS-PC to be configured with the following symbols for the underlying
RBBS-PC commands:
MAIN = normal: ABCDEFIJKOPRSTUVW
reconfigured: ABC>EFIJKOPRSTU\W
FILES = normal: DGLNPSUV
reconfigured: DGLNYZ^V
UTIL = normal: BCEFGLMPRSTU
reconfigured: !#E$<&M*()-+
GLOBAL = normal: H?QX
reconfigured: H?QX
SysOp = normal: 1234567
reconfigured: 1234567
LIBRARY =normal: ACDGLSV
reconfigured: []{G}:'
7.7 RBBS-PC's Support of Sub-menus
----------------------------------
Sub-menu support means that an item on a menu can itself be another menu,
so that selecting it results in a new menu being displayed from which the
caller can select yet another option.
The areas in RBBS-PC that can have sub-menu support include: answering
surveys, bulletins, doors, joining a conference, and the file subsystem
command to list directories.
A primary use of sub-menus is to simplify the user interface, chiefly by
allowing sub-categorization of the option. For example, suppose a SysOp
has a complex system of doors, including multi-user games (TREK, NAPOLEON,
3DCHESS), single-user games (D&D, R&R, PICKUP), and demonstrations (DBIII,
ORACLE, ADVENT). These could be presented on a single menu, such as:
The following Doors are available:
Multi-User Games
TREK - explore the galaxy, compete with 12 other players
NAPOLEON - be Russia, Italy, or England and fight the computer
3DCHESS - are you ready, Spock?
Single-User Games
D&D - the Unix dungeons and dragons!
R&R - welcome to Taipei, Tokyo, or Bangkok, soldier!
PICKUP - do you have what it takes?
Demos - all self running
DBIII - Special version of DB3 adopted for remote usage
ORACLE - see the power of SQL. Full screen if you emulate ANSI.
ADVENT - our own home brewed ...
With sub-menus, the user could see a single, 3 item menu
Doors are available for:
MGAME - multi-user games
SGAME - single-user games
PLANNING YOUR USER INTERFACE 7-9
DEMO - self running demos
When the caller picks one of these three, a new menu comes up that lists
the particular doors for each category. For example, after picking MGAME
the caller sees
Multi-User Games available include:
TREK - explore the galaxy, compete with 12 other players
NAPOLEON - be Russia, Italy, or England and fight the computer
3DCHESS - are you ready, Spock?
RBBS-PC's sub-menu capabilities allow SysOps to set up "tree-structured",
"key word" paths to options. Bulletins provide an example where this type
of structure can be very useful. Bulletins have two main uses: short,
system-wide announcements, and a standard stock of text files for policies
and procedures for a RBBS-PC. Some SysOps, however, have wanted to put up
an elaborate system of announcements, where in fact these "bulletins" are a
featured way of presenting data to callers. For example, an association
published 300 short pamphlets under a dozen categories, and wants to make
this information available on-line. Sub-menus fit this need very well.
The main bulletin menu could read:
Bulletins are available for:
NURSES - nurses
OB - obstetricians
PED - pediatricians
FAM - family physicians
Please type in the category you want:
OB, instead of being a bulletin, is a sub-menu that displays:
The following bulletins are available for OBSTETRICIANS. Each entry
shows the length and price per glossy copy.
NAT - natural childbirth, 8 pages, $3
MIDW - midwives. 20 p., $5
NUTRI - special nutritional needs of pregnant women, 25p, $6
FPLAN - family planning services, 40 p, $3
DRUG - drugs to beware when pregnant, 50 p., $5
When the caller picks MIDW, the associated document is displayed. In this
example, bulletins become a menu-driven way of selecting documents to
browse.
In order for the previous example to work, RBBS-PC utilizes "named"
bulletins. For example, selecting "B" as the bulletin prefix, the above
bulletins would be files BNAT, BMIDW, BNUTRI, BFLAN, and BDRUG. However,
RBBS-PC's "new bulletin search" function will only search for named
bulletins if they are listed in the file x.FCK (where x is the bulletin
prefix). Also, named bulletins are not listed in the "new" bulletin list
as numbered bulletins are.
7.7.1 How to Implement Sub-menus
--------------------------------
If "XXX" is an option on a menu, simply create a file named "XXX.MNU" that
has in it the text for the menu. Put this file in the same drive/path as
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-10
the non-menu options (e.g. where the "BAT" files go for doors, where the
bulletin files to display are put, where the directory files are). For
example, if "B" is the bulletin prefix, the above example would be
implemented by adding the files "BNURSE.MNU", "BOB.MNU", "BPED.MNU", and
"BFAM.MNU". Put these files on the same drive that the bulletins
themselves go.
The .MNU extension alerts RBBS-PC to the fact that the file is a menu.
Thus, RBBS-PC will only LIST the menu file, rather than ACT on it (e.g.
3DCHESS.BAT is a door to be run, while 3DCHESS.MNU is a menu to be listed).
7.7.2 Shared Options Across Sub-menus
-------------------------------------
RBBS-PC supports identical choices from different sub-menus. E.g. the main
menu has sub-menus A and B, and BOTH of these sub-menus could have an
option X on them, which triggered a different action (based on which sub-
menu it X was selected from). The way that this works is RBBS-PC searches
both for the global prefix and the user response as well as looking for the
current prefix and user response. If the bulletin prefix is "B", and the
structure of bulletins is as follows:
/ 1 BM is main bulletin menu, B is the prefix
A ---- 2 BMA.MNU submenu get with choice A
/ \ 3 BMB.MNU submenu get with choice B
/ BMC.MNU submenu get with choice C
/ / 1
BM --- B ---- 2 BMA1, BMA2, BMA3 bulletins active at BA
\ \ 3 BMB1, BMB2, BMB3 bulletins active at BB
\ BMC1, BMC2, BMC3 bulletins active at BC
\ / 1
C ---- 2
\ 3
7.8 RBBS-PC's "Macro" Command Support
-------------------------------------
RBBS-PC's "macro" support expands a single keystroke into multiple
keystrokes. It allows RBBS-PC to be tailored in even a greater variety of
ways than before because a single command can be set up to invoke a
sequence of multiple RBBS-PC commands. The concept is similar to the
keyboard macro function found in many terminal emulators, except that in
RBBS-PC the SysOp defines the macros and the caller invokes them
transparently without knowing.
Macros add a new dimension to RBBS-PC commands -- commands can be a full
word rather than just a single letter. A macro is invoked by a name up to
8 characters. For example, "DOOR" and "OPEN" can be used to invoke doors.
This makes it easy to make all commands available on a single level, since
D could trigger a download, while the word DOOR will trigger the door
function.
Macros can be used to abbreviate a longer series of commands. If the SysOp
wants to use "A)bandon conference", all that need be done is to add a macro
called "A" whose content is "J M" (join main). Or if N)etmail is to be
used to read Fido-net compatible message bases, a macro called "N" could be
set up as "D NETMAIL" (use door called NETMAIL). RBBS-PC thus can have
UNLIMITED commands.
A string of RBBS-PC commands can be stored in a macro for many different
types of purposes, including (but not limited to):
PLANNING YOUR USER INTERFACE 7-11
setting up demos,
showing a user what to do rather than just explaining it in words,
automated testing of RBBS-PC features
Macros can also be used to make the same type of function do different
work. For example, the B)ulletin command basically displays a text file.
Suppose an association wants to let persons order pamphlets and preview
them on-line. Rather than bury the ordering function insider A)nswer
questionnaire and the preview function inside B)ulletins, the commands
PREVIEW and ORDER can be added as macros, where ORDER stands for "A
ORDWHAT" AND "ORDWHAT" is a submenu listing what can be ordered. Each
option on the submenu is a questionnaire. PREVIEW similarly is "B PREWHAT"
where "PREWHAT" is a submenu listing the available pamphlets that are
stored as text files.
Macros can be built to provide interactive help to callers. For example,
you can put up a macro called EZDOWN to help people download. It explains
everything, asks for the file name and protocol, and tells the caller what
they should be doing on their end, and then drives the download.
Macros can be used to provide integrated data bases. Unlike
questionnaires, you can totally control how data is written to a file. You
can put in labels, or data only, put the values in quotes, separate the
values by commas, etc. This is done by creating a template into which data
values are written.
Macros can be used to give "tours" of your RBBS-PC -- to showcase new or
special features.
Macros can be controlled via security level access, just like regular
commands, and they can be forced to operate only in certain contexts.
Macros can be
- invoked anywhere within RBBS-PC -- including questionnaires,
- unlimited in length,
- used even when the caller has "turbo" key feature enabled,
- used with SmartText (see section 7.9),
- used to store responses that can be manipulated later, and
- used to support graphics versions of text.
It is important to remember that a macro will be ignored if its name is the
same as any command. To replace a command with a macro, you must insure
that the letter for the command has been reassigned. CONFIG parameters
30-34 allow such reassignments to be easily accomplished.
Some contexts will not accept macros, such as when RBBS-PC prompts for a
search string.
Macro commands with more than one letter override all others. This means
that the macro interpretation will prevail if more than one interpretation
is possible. For example, in the absence of macros the command "door"
would the interpreted as the command "d", so that saying "door" in the
files section would be download. But a "DOOR.MCR" would be executed
instead when it exists. One letter commands, however, will be executed
when they match a command letter, and so any macros will be ignored that
have the same one letter name the same as a command.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-12
7.8.1 How to Set Up "Macros"
----------------------------
To use macros, two CONFIG parameters must be specified: the drive/path
where macro files are stored (CONFIG parameter 79) and the extension the
macro files will have (CONFIG parameter 80). The defaults are "C:" and
"MCR". To create a macro named X, simply create a file with prefix X and
the macro extension and place in it the macro drive/path. If you are not
using any macros, RBBS-PC will run faster if you specify NO macro extension
in CONFIG parameter 80.
The first line within a "macro" controls access to the macro, both by
security level, and a limitation on the scope of the macro, in which it
will be operative, including
- anywhere inside a section
- anywhere inside a command
- only at a section and not inside.
The format of the first line is:
<SecLevel>/<constraint>
where <SecLevel> is the minimum security required to run the macro, and
<constraint> is the section (M for main, F for file, U for utility, or @
for library) and command letter the macro is confined to (use original
command letter, not the reassigned ones). For example
4/M
means that security level 4 is required, and the macro runs only at or
inside the main section prompt.
5/MB
means that security level 5 is required and the macro runs only at or
inside the main section bulletin command. Thus the macro file 1.mcr
2/MJ
{EN
RBBS
means that when inside the main J)oin, the text "RBBS" will be substituted
for "1". (So "J 1" does the work of "J RBBS".) The "{EN" means not to
echo what the macro substitutes (user does not see "RBBS").
To make a macro operative only at a section prompt and not inside, add a "
/" to the end of the section constraint. For example,
4/M /
means that the macro applies only at the main section prompt. For example,
the macro SP.MCR
4/M /
{EN
J SEMIPRV
will substitute "J SEMIPRV" for "SP" when at the main prompt, but NOT for
"SP" inside the message read command ("R SP L").
PLANNING YOUR USER INTERFACE 7-13
Note: a macro will be ignored if its name is the same as a command symbol.
To use 1, 2, 3, etc. for macro commands, you must disable or substitute
other symbols for the SysOp commands.
The first line of a macro must be the minimum security level to use the
macro. The macro will simply be ignored if the caller has insufficient
security. The second line will be parsed and replace the macro name. The
remaining lines will be read from disk and processed as required.
Macro commands have the same structure as SmartText variables:
<command prefix><command name>
where <command prefix> is the SmartText command specified in CONFIG. The
symbol "{" (ASCII 123) is the default. The <command name> consists of two
characters. Lines that are not valid macro commands are simply passed to
RBBS-PC as if the user had typed them in. There are three differences
between SmartText variables and macro commands:
(1) Macro commands must be the first three characters on a line, whereas
SmartText variables can occur anywhere on a line.
(2) Macro commands can have an argument after the command name, and(
(3) A macro command can apply to a block of lines following it.
7.8.2 Macro Commands
--------------------
RBBS-PC "Macro" Commands include the capability of having commands executed
within the "macro" rather than simply passing keystrokes to RBBS-PC. In
all prompts and blocks, substitution is supported for both stored answers
SmartText variables. The following is a list and description of valid
"macro" commands:
*0 - display what follows on the line with no carriage return.
*1 - display what follows on the line with a carriage return.
*B - display what follows on subsequent lines.
*F - display the named file that follows.
nn - display a prompt and store result in work variable nn.
WT - pause for the number of seconds specified after "WT".
>> - append the following block of text to the file specified.
ST - Stack the characters immediately following the "ST".
M! - Execute the named macro that follows on the same line.
ON - Case logic for branching within macros based on stored results.
EY - Echo the text passed in macros as keystrokes.
EN - Do not echo the macro keystrokes.
<< - Display fields from a file in a form.
:= - Assign value to a work variable
LV - Verify that answer of one in a list
NV - Verify that answer is between two integers
CV - Verify that answer is between two character values
LO - Set location for Fast File Searches for download, upload, view
The syntax and an example of each command follows:
*0 - display what follows on the line with no carriage return.
{*0Press any key to continue
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-14
*1 - display what follows on the line with a carriage return.
{*1{FN, I hope you enjoyed your tour of the board!
The caller's first name is substituted for the SmartText variable
"{FN."
*B - display what follows on subsequent lines, each line with a carriage
return, up to the line beginning with "{END".
{*B
This is an example of a macro's ability to display
multiple lines. The macro command is
{*B
and it will display all lines until it encounters one
beginning with {END. Like it, {FN?
{END
The caller will seen everything between the first and last lines, with
the first name substituted into the last line displayed.
*F - display the named file that follows.
{*F L:\RBBS\HELP.LST
will display the file HELP.LST.
nn - use the text that follows on the line as a prompt and store the answer
in an internal working variable numbered nn. nn must be two digits
and can be 01, 02, 03, ..., 99. CONFIG parameter 94 controls the
maximum # of work variables.
{01Please enter the Department you work for:
{02Please enter your Office number:
This will store the answers in work variable # 1 and 2, which can be
subsequently referenced as "[1]" and "[2]". You can have as many work
variables as specified in CONFIG parameter 94. Variables that are
reused have their values overwritten.
WT - pause for the number of seconds specified after "WT".
{WT 2
will wait for 2 seconds.
>> - append the following block of text to the file specified on this line.
{>> C:MACRO.DAT
"{FN","{LN","[1]","[2]"
{END
will append the following line to the file named MACRO.DAT on drive
C:, assuming the caller is KEN GOOSENS, and he responded to the above
prompts for Department with "Controller" and Office # with "107".
Then the line what would be written out is:
"KEN","GOOSENS","Controller","107"
PLANNING YOUR USER INTERFACE 7-15
As many lines can be included as desired. Simply end the block to be
written out with "{END" as the beginning of the line.
Some data base managers want fixed length files and this is possible
in the macro append. Just add "/FL" on the macro command line.
Rather than replace, the substitution will overlay the line at the
"[", thus keeping the output fixed length. Lets suppose that the
first work variable has "A" as a value, the second work variable has
the value "123456", the third work variable has "Henry" as a value,
and the caller's first name is KEN. Then
{>> C:\RBBS\DAT.FIL /FL
[1][2]....[3]...............{FN........
{END
would add the following line into DAT.FIL
A 123456.Henry.............KEN.........
Normally, blanks would be put where dots are show.
ST - Stack the characters immediately following the "ST".
{ST
will stack a carriage return (no characters). And
{STD [1] [2]
would stack "D RBBS-EXE.ARC Z" - as if they were typed and ENTER
pressed - if the first work variable had "RBBS-PC.EXE" and the second
work variable held "Z". It is important to note that "macros" are so
transparent to RBBS-PC that if you use macros to display text at an
RBBS-PC prompt like "Enter command? ", RBBS-PC will continue to sit
there waiting for an answer. A stacked carriage return at the end
will cause the prompt to be redisplayed, though the effect of the
stack will vary with the particular prompt.
M! - Execute the named macro that follows on the same line. E.g.
{M! ORDER
will execute the macro called ORDER. RBBS-PC does NOT return to the
invoking macro when the named macro is complete. Also, The full file
name of the macro to execute is not here used (i.e. ORDER.MCR), only
the file prefix -- ORDER.
As is shown in the example of the ON command, the macro name can have
a drive/path and/or extension. If only a prefix is put in, RBBS-PC
will automatically add the drive/path and extension for macros
specified in CONFIG parameter 79 and parameter 80. Putting in a
drive/path/extension that is different from CONFIG's assures that no
caller can invoke the macro -- it only can be used internally by your
application.
ON - Case logic for macros. This allows responses to be tested against and
branching logic developed within a "macro". An example would be:
{ON 1
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-16
{==A
{M! D:\HIDDEN\CHOICEA.MCR
{==B
{*1You have selected option B
{02Why did you select B?
{==C
{M! D:\HIDDEN\CHOICEA.MCR
{END ON
EY - Echo the text passed in macros as if keystrokes. The default is to
echo.
EN - Do not echo the macro keystrokes. An example would be:
{EN
{*1 The following commands will be executed but now shown
{01 Press Enter when ready
R L
A
{EY
{*1 now you will see the responses to the prompts
{01 Press Enter when ready
R L
A
<< - Display fields from a file in a form. This is one of the most
powerful macro commands. It allows data to be stored in compact, data
format but retrieved into a form for display to a caller. There are
5 parameters that can follow the macro command:
<file name> <file format> <data#> <submode> <rec-pause>
where:
"<file name>" is the name of the data file that has records to read,
"<file format>" is "/V" if data is stored in variable length format
and "/F" if fixed length format,
"<data#>" is the number of separate fields in a record for variable
length data and the length of the data if fixed length,
"<submode>" is the mode used to substitute data in the following form
"/FL" if the form is fixed length, meaning that data is overlaid into
the form so as not to change any lengths.
"<rec-pause>" should be "/1" if you want to pause after each record
rather than when the screen fills.
An example of a "macro" that uses this capability is as follows:
{*1 -TOPIC- - DATA # - - VOICE # - -First Name- -Last Name-
{<< C:\RBBS\RHLP.DAT /V 5 /FL
[1] [2] [3] [5] [4]
{END
Note that spaces occur after the "[4]". If the file RHLP.DAT contains
"DOORS","703-978-6360","0","Ken","Goosens"
PLANNING YOUR USER INTERFACE 7-17
"PROTOCOLS","407-627-6969","407-627-9767","Doug","Azzarito"
then the caller would see
-TOPIC- - DATA # - - VOICE # - -First Name- -Last Name-
DOORS 703-978-6360 0 Ken Goosens
PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito
The same example using fixed length data would be
{*1 -TOPIC- - DATA # - - VOICE # - - Name -
{<< C:\RBBS\RFLH.DAT /F 69 /FL
[1](34:12) [1](46:12) [1](58:12) [1](1:33)
{END
where RFLH.DAT contains:
Ken Goosens DOORS 703-978-63600
Doug Azzarito PROTOCOLS 407-627-6969407-627-9767
This would produce the following for the caller:
-TOPIC- - DATA # - - VOICE # - - Name -
DOORS 703-978-6360 0 Ken Goosens
PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito
Note that work fields support sub-field references in the format:
[n](x:y)
where n is the work field number, "x" is the beginning column, and "y" is
the # of bytes to get. If work field two had a value "123abcde" then
"[2](3:4)" would have "3abc" as its value. Fixed length records are always
referenced as work variable one.
:= - Assign a value to a work variable. Work variables can be assigned a
value inside a macro. The command to do this is ":=". E.g.
{:= 5 OK
assigns string "OK" to work variable 5.
LV, NV, and CV - Macros can edit the responses to questions. Edits can
constrain the answer to
- one of a list
- a numeric value between two values
- a character value between two values
An editing constraint must be put in front of the actual macro
question it applies to, and a constraint applies only to the next
question and does not remain operative.
The commands for these are respectively "LV" (List Verify), "NV"
(Numeric Verify), and "CV" (Character Verify). The list verify uses
the first character after the command as a delimiter between valid
responses. E.g. "{LV;R;A;E;" means that only "R", "A", and "E" will
be accepted as answers ("{LV/R/A/E/" would have the same effect).
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-18
Semi-colon is the best delimiter in general because it cannot be
entered as a value.
Numeric and Character verify check inclusive ranges. Thus "{NV 7 11"
will accept 7, 8, 9, 10, or 11. The numeric value must be an integer
between -32,768 and 32,767. To accept answers B through E, the macro
edit command is "{CV B E".
Whenever an answer fails an edit, the message "Invalid answer <...>"
is given with the answer received between brackets, and the question
is asked again. An example of a macro with edits is:
4
{*1 Verification macro
{*1 now checking list...
{LV;A;F;W;
{01 Enter A, F, or W
{*1 now testing numeric range...
{NV 5 15
{01 Enter a number between 5 and 15
{*1 now testing character range...
{CV D J
{01 Enter a character between D and J
LO - Sets location that a file is to be searched for in an upload,
download, or view request. Followed by a drive path. Useful when
want to have a macro execute in front of a download or upload for a
file which is really available (see section 12.9). Applies only to
Fast File Search. For example,
{LO F:\DF1\
would set the file location to drive F subdirectory DF1.
7.8.3 A Sample Macro
--------------------
Suppose A)bandon conference is to be implemented in RBBS-PC. To do this,
the command A)nswer questionnaires must be assigned a different letter.
Else A will always invoke answer instead. Then the macro file could
contain
5
J M
The command "A" will then be followed by "Rejoining MAIN". Incidentally,
if the macro had been implemented by
5
J
M
The only difference is that the prompt for what conference to join will be
displayed, "M" then would be displayed as if the caller had typed it, and
then main would be rejoined. The difference is caused by the fact that the
first line after the security level is what replaces the macro name, so in
the first case "M" preempts the prompt but not in the second.
PLANNING YOUR USER INTERFACE 7-19
7.8.4 On-line Data Base With Macros & Questionnaires
----------------------------------------------------
RBBS-PC provides the SysOp with the ability to offer callers access to an
on-line database both internally (using macros and questionnaires) and
externally to RBBS-PC (see Appendix R).
RBBS-PC's internal Remote Data Base feature gives the SysOp the ability to:
- set up unlimited numbers of named data bases
- set up menus to interact with the user
- prompt users for data
- use Metavariables - both work variables and SmartText variables.
- store user's answers in work variables. Any subfield in a work
variable can be referenced.
- display, or store all metavariables
- process commands conditionally
- save Metavariables to file through templates, allowing data to be
stored in virtually any format desired
- retrieve data into templates for display.
- do full screen data entry
RBBS-PC's support for "full screen" questionnaires and macros takes some
work on the SysOp's part. The SysOp must use ANSI screen commands. The
SysOp must then arrange to transmit the "template" that clears the callers
screen and writes the appropriate static text (lines, labels, etc.) on the
callers screen. Then the data the user is to see is transmitted onto the
caller's screen. The "full screen" support does not allow the caller to
use keys like tab and cursor arrows to move around on the screen. It is
"full screen" in the sense that the caller sees all the data that is to be
entered and the cursor moves from field to field.
On-line Database Example
------------------------
This application manages a data base of callers who are willing to help
with RBBS-PC by topic. It is controlled at a high level by the following
questionnaire.
C:DUMMY.DAT,4
* This questionnaire is for finding help with RBBS-PC by topic.
* Please register yourself if you
* - are willing to help others, and
* - know enough about a topic to help
*
* Examples of topics people need help with:
* Desqview Modem models (HST, Everex, USR Internal, etc.)
* PC-Slaves Protocols Conferences FMS
* Doors DoubleDos Sub-boards PUI
* Questionnaires 10-Net Macros Uploads
* MU-Purge File maint. Personal dnld Caller Analysis
*
:-[prompt]-
T
? V)iew database, E)nter new data, Q)uit (V,A,Q)
=V-[view]-=E-[add]-=Q-[quit]-= -[prompt]-
:-[view]-
M C:\RBBS\VIEWHELP.MCR
>-[prompt]-
:-[quit]-
@
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-20
:-[add]-
* 703-978-6360
?1 BBS data number
* 703-978-4339
?2 Voice # (evening, 0 not to give)
* You can specify as many topics as desired, one at a time.
*
:-[topic]-
?3 RBBS-PC topic you will help others with, or Q)uit
=Q-[prompt]-= -[addrec]-
:-[addrec]-
* -Topic- - Data # - - Voice # - Last Name First Name
*/FL[3] [1] [2] {LN {FN
T
?Really add this record (Y,N)
=Y-[really]-=N-[topic]-= -[addrec]-
:-[really]-
M C:\RBBS\ADDHELP.MCR
>-[topic]-
Two macros are used by this questionnaire:
VIEWHELP.MCR for displaying the data base, and
ADDHELP.MCR for appending new data to the data base.
VIEWHELP.MCR contains
5
{*1 -Topic- - Data # - - Voice # - Last Name First
Name
{*F RBBSHELP.DAT
ADDHELP.MCR contains
5
{>> RBBSHELP.DAT /FL
[3] [1] [2] {LN {FN
{END
Full Screen Example
Full screen is available only in a color graphics version of questionnaires
and macros. A long application for collecting BBS information is given in
these following files:
REGRBBS.DEF - Questionnaire driver, TTY version
REGRBBSC.DEF - Color graphics version of questionnaire driver
VUNRBBS.MCR - View data base macro, TTY version
VUNRBBSC.MCR - View data base macro, Color graphics version
SVRBBS.MCR - Macro to save data to a comma separated data file
These files can generally be download from most bulletin board systems.
However, they are definitely available on Ken Goosens' RBBS-PC system at
(703) 978-6360.
Hints for Building Remote Data Base Applications
------------------------------------------------
Generally you will have:
PLANNING YOUR USER INTERFACE 7-21
- a questionnaire driver that gives caller option to exit, view
database, or Enter new data
- a macro to retrieve data from file to a form
- a macro to save data in a data base format
- a data entry routine in the questionnaire.
Creating a "full-screen" application is more complicated that than a line-
at-a-time (i.e. TTY) application. For full-screen applications, you will
want to:
- paint a template with everything but the data values, such as row and
column labels and titles.
- clear out the existing values in a form and then put in the new
values.
Only the changes to the screen are transmitted rather than retransmitting
the entire screen when only a part changes.
ANSI commands are used to control the screen. Where [ESC] stands for the
one-character Escape (ASCII 27), the most useful ANSI commands to know are:
[ESC][2J - clear the screen.
[ESC][K - clear from current cursor position to end of line. Cursor
position after clearing is same as before.
[ESC][X;Yf - position the cursor on row x and column Y. E.g.
"[ESC][5;10f" positions on column 10 of row 5.
Case is significant in ANSI commands, so beware that "[ESC][k" will NOT
clear to end of line, and "[ESC][1;7F" will not position the cursor.
You can use ANSI commands to set color and blink characters. An easy way
consistent with RBBS-PC is to set colors using the SmartText variables C0,
C1, ..., C4, where 1-4 are the colors set in CONFIG parameter 323,
parameter 324, parameter 325, and parameter 326. C0 is "emphasis off," and
restores normal text color preference of the caller. An example that
clears the screen, sets color to 1, positions on line 1, column 15, prints
"-Sample Title-", sets color to caller's text preference, prints 2 spaces,
and then prints value of work variable 1 is as follows:
[ESC][2J{C1[ESC]1;15f-Sample Title-{C0 [1]
7.9 RBBS-PC's "SmartText" Variables
-----------------------------------
SmartText allows the SysOp to substitute pre-defined variables in text
files as menus, bulletins, help, welcome files, as well as macros and
questionnaires. This allows the SysOp to present to each caller an
interface that is not only "programmable", as discussed in section 7.6, but
also tailored to the specific caller.
Some applications for SmartText include: addressing the caller by name, as
well as referring customized variables for the caller, such as city/state.
For example, the welcome file could say, "Hi, <first name>, how's the
weather in <city/state>?". SmartText variables can also be used for status
line reports in menus, showing such things as security, minutes remaining,
and current time.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-22
To utilize RBBS-PC's SmartText files, CONFIG parameter 17 must be set to
the decimal value of a delineation character that the text editor used by
the SysOp can handle. The character you select should have three
characteristics:
1. It should be visible on the screen and when printed. This allows
the SysOp to see where the control sequence is when designing the
text files to be used as SmartText files.
2. It should not be a character that might be used for any other
purpose in the text files. The character can still be used in
text files, but the chances are slight that RBBS-PC will
interpret the character as a SmartText sequence.
3. It should not be a character that might be interpreted, when
printed, as being a printer command (i.e. start double spacing).
IMPORTANT: While RBBS-PC currently allows you to select the SmartText
character, we STRONGLY suggest you use the default character
(the { character, decimal 123). Future versions of RBBS-PC
will no doubt rely heavily on standard SmartText, and as
such will probably NO LONGER allow you to change this
character.
CONFIG parameter 17 can have any value between 0 and 255. If 0 is
selected, RBBS-PC's SmartText capability will be turned off.
A RBBS-PC SmartText control sequence consists of the control character that
was selected in CONFIG parameter 17 followed by a SmartText double-
character command. These SmartText double-character commands MUST be
entered as upper case characters! There are two kinds of SmartText
variables: those which substitute text, and others which control how
substitution is done. The commands are:
COMMAND NAME MEANING
BD "Bytes Downloaded" Displays the bytes downloaded today.
BN "BBS Name" Displays the name of the BBS.
CS "Clear Screen" Overrides RBBS-PC's automatic screen depth
management so that the next "Press Enter to
Continue" will not come halfway through a page.
CT "City/state" Displays the caller's city & state.
C0 "Color 0" Resets color to the user's selection for text.
C1 "Color 1" Changes color to the user's selection for
Foreground Color One.
C2 "Color 2" Changes color to the user's selection for
Foreground Color Two.
C3 "Color 3" Changes color to the user's selection for
Foreground Color Three.
C4 "Color 4" Changes color to the user's selection for
Foreground Color Four.
DB "Dnld (tot) Bytes" Inserts the total number of bytes ever downloaded
by the caller.
DD "Downloads Today" Inserts the total number of files downloaded by
the caller today.
DL "DownLoads" Inserts the total number of files ever downloaded
by the caller.
DT "Date" Inserts the current date, MM-DD-YYYY, into the
text file.
PLANNING YOUR USER INTERFACE 7-23
FI "FileName" Inserts current work Filename into the text file
FN "First Name" Inserts the user's FIRST NAME into the text file.
FS "First Name SySop" Inserts the SysOp's FIRST NAME into the text file.
LN "Last Name" Inserts the user's LAST NAME into the text file.
LS "Last Name SysOp" Inserts the SysOp's LAST NAME into the text file.
ND "Node Number" Inserts the RBBS-PC Node Number for this node.
NS "Non Stop" This causes the rest of the current file to be
displayed in RBBS-PC's "none stop" mode. Page
breaks will be ignored following a NS command.
PB "Page Break" Causes RBBS-PC page break message, "MORE
(Y/N/NS/A)" or the "PRESS ENTER.." prompt to
appear after the line is printed.
RP "Reg Period" Inserts the number of days in the registration
period.
RR "Reg Remaining" Displays the days remaining in the caller's
registration period.
SL "Security Level" Inserts the user's current security level into the
text file.
TE "Time Elapsed" Inserts the user's elapsed session time (hh:mm)
into the text file.
TM "Time" Inserts the time (hh:mm AM/PM) into the text file.
TN "Trim NO" Substitute as is (the default)
TY "Trim YES" Remove leading and trailing spaces first
Note: a setting for trimming remains in effect until another trim
command is encountered.
TR "Time Remaining" Inserts the number of minutes left in the user's
session into the text file.
UB "Upload Bytes" Displays the total number of bytes ever uploaded
by the user.
UL "UpLoads" Displays the total number of file ever uploaded by
the user.
VN "Overlay NO" Insert into the text file (the default).
VY "Overlay YES" Overlay into the text file (do not change length)
Note: an overlay setting remains in effect until explicitly replaced.
When designing SmartText files, each SysOp should take into account that
the some of the SmartText commands (i.e. the user's name) may significantly
extend the length of a line. It is important that this line elongation be
taken into consideration so that, when the actual text substitution occurs,
the line seen by the caller does not exceed 80 characters.
What follows is an example of a SmartText file that demonstrates how all of
the above commands might be used. The following example assumes that
CONFIG parameter 17 has been set to the decimal value 123 for the SmartText
delineation character -- {.
Introducing...{C1SmartText!{C0
RBBS-PC allows the SysOp to customize the text seen by each caller.
For instance, if the SysOp wanted to make sure this message didn't
scroll off the screen, he could pause the display like this:
{PB
Or, the SysOp may want to show the caller that today's date is {DT and
the time is {TM. The SysOp may even want to include a personal
greeting to {FN {LN.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-24
The SysOp can tell the caller that their security level is {SL and
that they have been on-line for {TE, and have {TR minutes left in this
session.
This kind of capability illustrates RBBS-PC's on-going commitment to
nurturing each SysOp's creativity and avoiding the dogmatic.
7.10 "Colorizing" the RBBS-PC User Interface
--------------------------------------------
"Colorization" refers to the utilization of color within RBBS-PC text files
and prompts. RBBS-PC has long supported graphics versions of external text
files, and is even distributed with graphics menus. RBBS-PC supports
"colorization" as follows:
1) In files shown to the callers including:
All menus,
All bulletins,
The Welcome file,
The file for new users,
All on-line help files,
Standard file directories, and
FMS file directories (see item 6 below).
2) Via highlighted text
in searches of messages,
in searches of files,
in announcing new personal mail waiting,
for locked out users, and
the SysOp user maintenance (function 5).
Highlighting supports a limited but extremely functional use of
colorization - to make it easy for the caller to spot significant bits of
text on a screen.
3) Within the Programmable user interface (PUI).
The PUI file can have graphics versions just like text files. The file
XMAIN.PUI that was used in the example in section 7.6.2 can have a
graphic's equivalent named XMAING.PUI and a color equivalent named
XMAINC.PUI. Color codes can be embedded in the prompts in the PUI as well
as external text files. Each SysOp has total freedom to colorize prompts
as well as menus.
4) Within text internal to RBBS-PC.
This applies to standard (non-PUI) prompts, such as the main command
prompt, and to formatted reports, like the message scan and message read.
This type of "colorization" is controlled by whether highlighting has been
turned on in CONFIG.
5) Within RBBS-PC's "short" prompts.
Caller foreground color 4 is used to mark the commands the user can type.
Emphasis is used to mark the default selection. This colorization is based
on a scan of the text to be printed:
[...] : will be highlighted (default answer)
(xxx) : will be put in foreground color 4 (text to type in): if xxx
is not longer than 2 characters and is in caps
<...> : will be put in foreground color 4 (collective choices) and
if there are words before this, the first will use
foreground 1 and the second, foreground 2.
PLANNING YOUR USER INTERFACE 7-25
"Short" prompts colorization applies to ALL text displayed by RBBS-PC
before an answer is expected. For example, by using the above conventions,
questionnaires can be colorized. This is controlled by whether
highlighting is on.
6) Within FMS file directories.
The "colorization" of the FMS file directories is based on the four colors
specified in CONFIG and is controlled by whether or not the caller has
selected to be in color graphics mode or not.
There are two extremes on the use of color: use none or use it everywhere.
By using no colorization, RBBS-PC's performance is optimized. RBBS-PC does
not have to go through the overhead of transmitting special instructions to
control the caller's screen. The two chief functions of BBSs, transmission
of textual information and file exchange, do not essentially involve the
use of color.
Of course, there are those who want their RBBS-PC's visual displays to
convey as much as the text or the files themselves (i.e. the message is in
the medium). These are the SysOps would elect to use color everywhere.
With the use of color, plain text begins to look drab and uninteresting and
attention tends to focus on the colorized text. For this reason, some
SysOps find it difficult to use color in some places and not in others.
Colorization is implemented in RBBS-PC with ANSI display commands. In
order for a caller to see the colors as RBBS-PC displays them, the terminal
emulator used by the caller MUST be ANSI-compliant. CONFIG allows the
SysOp to activate and customize colorization on screen 17, "RBBS-PC Color
Parameters".
1) Use CONFIG's parameter 321 to put in a string for turning EMPHASIS on.
The recommendation is a bright foreground on red background
("[27][1;41m").
2) Use CONFIG's parameter 322 to set the string for normal text. This is
the general default color and is used to turn off emphasis. The
recommended color is amber (normal yellow) ("[27][0;33m").
3) Use parameter 323, 324, 325 and 326 of CONFIG to set the four caller
foreground colors. CONFIG uses natural language phrases to set these,
so it is very easy. The recommendation, in order, is:
bright green,
bright yellow,
bright purple, and
bright cyan.
These colors are all used in the message header and general command prompt.
Foreground 4 is used to highlight the commands the caller actually needs to
type in to select that option.
No colors will be displayed if these parameters are set to empty strings.
Callers can turn off the colorization simply by going into Utilities and
T)oggle H)ighlite to "off". The default in RBBS-PC is for colorization to
be OFF.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-26
Colorization is based on the ANSI standard. Special codes are sent by
RBBS-PC to the callers system, which must then be interpreted by the
caller's communications software.
7.11 RBBS-PC's Automatic Operator Page Option
---------------------------------------------
RBBS-PC will "automatically page" the SysOp whenever a specified caller or
group of callers logs on to RBBS-PC or joins a specific "sub-board". The
selection criteria can be a specific caller's name, a range of security
levels, or whether the caller is a new user. A SysOp may wish to be
notified for any number of reasons including:
- A caller has been causing trouble on the bulletin board and needs to
be monitored.
- The SysOp wants, for security reasons, to be notified when anybody
logs on with a SysOp security level.
- The SysOp wants to chat with a friend but does not want to continually
monitor RBBS-PC's activity.
AutoPage is controlled by a file whose name is specified in CONFIG
parameter 18 (the default name is AUTOPAGE.DEF). Each line in the file is
a separate AutoPage command. The line contains 4 parameters separated by
commas. The format is
<condition>,<notify caller?>,<# of times>,<music>
<condition> Can be a NAME enclosed in quotes, the string
"NEWUSER", or a security level range specified in
the format
/<min sec>/<max sec>
where:
<min sec> is the minimum security level
<max sec> is the maximum security level
<notify caller?> Is "N" if the caller also is to be notified that
the SysOp has been notified when the caller logs
on. Anything else means the caller will not know
that the SysOp has been paged automatically.
<# of times> Is the number of times that the PC's speaker will
be sounded.
<music> Is a BASIC music command to be used instead of a
beep. If nothing is specified, a beep will be
used.
Warning: on some PC's the playing of music produces "out of string space
errors". Test any music before using. Beeps always work fine.
Examples:
"SEXY DEVIL",,1,L4EDC AutoPage when a caller named SEXY DEVIL logs on,
do not notify the caller, and play "L4EDC".
"GREGG SNYDER",N,2, AutoPage when GREGG SNYDER logs on, notify the
caller, and beep the speaker twice.
PLANNING YOUR USER INTERFACE 7-27
"NEWUSER",,1, AutoPage when any new caller logs on, do not
notify the caller, and beep the speaker once.
/10/12,N,2, AutoPage when anyone with security 10 through 12,
inclusive, logs on, let them know that the SysOp
wants to be notified that they are on, and to beep
the Speaker twice.
The status line at the bottom of the RBBS-PC screen will read "AP!" for the
duration of the caller's session if RBBS-PC has automatically paged the
SysOp. This allows the SysOp to know that the AutoPage took place, even if
the SysOp was not present at the beginning of the call.
If the caller triggers more than one AutoPage command, the first condition
encountered will be used.
Since each "sub-board" can have a different AutoPage command file, the
SysOp has the option to be automatically paged based on different criteria
for each "sub-board".
7.12 Enhancing the File View Function
-------------------------------------
Within the File Subsystem of RBBS-PC the V)iew function, allows the caller
to get a list of files that are "archived" inside a single file. RBBS-PC
supports .ARC, .LZH, .PAK, and .ZIP compression formats, as well as ANY
format using SysOp-installed external procedures.
RBBS-PC assumes that the file extension will identify the type of
compression. Hence, the SysOp can install a View function for files with
extension ".XYZ". All the SysOp must do is put a .BAT file with the name
"Vxyz.BAT" on the same disk and path specified for COMMAND.COM via CONFIG
parameter 105. If such a file is present, RBBS-PC will shell to the
command in Vxyz.BAT whenever a caller asks to V)iew any file with the
extension .XYZ. SHELLing requires extra system RAM beyond what RBBS-PC
uses. If your system has little or no free memory, you may be limited to
using the internal V)iew feature of RBBS-PC.
RBBS-PC includes the following files for external View support:
ARCVIEW.COM Compiled C program for view of DWC, PAK, ZOO, and ARC
files. Used in VDWC.BAT, VZOO.BAT.
VDWC.BAT Processor for DWC files
VZOO.BAT Processor for ZOO files
Each BAT file contains in it:
ARCVIEW [1] > [2]
RBBS-PC will SHELL to the above program (not to the BAT file) after first
substituting the name of the file to be listed for "[1]" and the name of
the file to place the results of the listing for "[2]". The ">" is the DOS
"redirect" function, which causes the output to be placed in the file
instead of on the local screen.
The file specified in [2] is named "NODE?WRK" when the wildcard "?" is the
node id (1,2,3,...).
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-28
How to Implement Your Own View function
---------------------------------------
Your view program must have a way to receive from RBBS
- the name of the file to list
- the name of the file to write the listing to.
RBBS-PC will interface with your program in two different ways, depending
on how many lines your BAT file contains.
If the BAT file contains exactly 1 line, RBBS-PC will shell to the line in
the BAT file and not to the BAT file itself. RBBS-PC will dynamically scan
for "[1]" and "[2]" in the line and substitute the names of the file to be
listed and the file to write the results to, respectively. Everything else
will be left intact.
If the BAT file contains more than one line, RBBS-PC will shell to the BAT
file, passing as command line parameters the name of the file to list, and
the name of the results file.
For example, the following BAT file could be used:
ECHO OFF
ECHO %1 >> VIEW.LOG
ARCVIEW %1 > %2
ECHO ON
The statement "ECHO %1 >> VIEW.LOG" will create a list of all files
selected for view. ">>" means to append the view file name to a file
called "VIEW.LOG".
Using ZIPTV
-----------
Ziptv is a program distributed by Samuel H. Smith which supports not only
View, but the ability to list any file inside of a ZIP file, thus allowing
users to view documentation before downloading a file. Many SysOps will
want to install ZIPTV to replace the internal RBBS-PC View function. To do
so, create a VZIP.BAT as follows:
DEL %2
<path>ZIPTV -P%3 %1
Where <path> is the drive and subdirectory where you have placed ZIPTV.EXE.
7.13 Bulletins and News
-----------------------
RBBS-PC has very powerful and flexible features for broadcasting system-
wide information to callers. The following table describes the various
NEWS options:
PLANNING YOUR USER INTERFACE 7-29
┌───────────────────────────┬─────────────────────────────────────────────┐
│ When the caller will see │ Which file will the caller see │
│ the news │ │
├───────────────────────────┼─────────────────────────────────────────────┤
│Every time the caller logs │The file PRELOG is displayed before callers │
│on. │are asked their names. This information │
│ │should be kept very brief. │
├───────────────────────────┼─────────────────────────────────────────────┤
│Only when a NEW USER logs │The file NEWUSER is shown to new users only │
│on. │the first time they log on. │
├───────────────────────────┼─────────────────────────────────────────────┤
│On every call, after the │The file WELCOME is displayed after a │
│caller logs on. │successful logon. For graphic and color │
│ │versions of this file, see section 6.3. │
├───────────────────────────┼─────────────────────────────────────────────┤
│Only when the SysOp has │The NEWS file is displayed if the date of │
│updated information since │last log on is the same or earlier than the │
│the last time the caller │date of the news file. The news file also │
│was on the BBS. │can be read by using the "B N" command │
│ │(Bulletin News). │
├───────────────────────────┼─────────────────────────────────────────────┤
│Every time the caller logs │The logoff questionnaire, EPILOG.DEF is │
│off. │processed at logoff, and can be used to │
│ │display news at this time. See section 19. │
├───────────────────────────┼─────────────────────────────────────────────┤
│Available on request by │The RBBS-PC general Bulletin files. │
│the caller. │ │
└───────────────────────────┴─────────────────────────────────────────────┘
General Bulletin Files
----------------------
General bulletins are text files prepared by the SysOp that can be viewed
by the callers when they first log on, or at any time during the caller's
session. To configure bulletins, you must first decide if you will used
NUMBERED bulletins, NAMED bulletins, or both. The only difference between
numbered and named bulletins is in how RBBS-PC scans for new bulletins when
a caller logs on. With numbered bulletins ONLY, RBBS-PC uses the number of
bulletins specified in CONFIG parameter 62 to find new bulletins. If the
SysOp uses NAMED bulletins, each bulletin must be identified to RBBS-PC (in
the file BULLET.FCK) in order to scan for new bulletins.
To create a bulletin, use CONFIG parameter 61 to set the location and name
of the bulletin menu, and set parameter 63 to the desired bulletin prefix.
If you are using numbered bulletins, also set parameter 62 to the number of
bulletins.
Ex: Set parameter 61 to: C:\RBBS\BULLETIN\BMAIN.MNU
Set parameter 63 to: B
When RBBS-PC looks for bulletins, it will use parameter 61 for the location
of each bulletin, and parameter 63 to build the file name. If you would
like a bulletin named TEST, RBBS-PC will look for the file
C:\RBBS\BULLETIN\BTEST.
Any TEXT editor can be used to create bulletins. The bulletin can contain
ASCII text, extended ASCII graphics, or ANSI color. By naming the
bulletins properly, RBBS-PC's graphic support will display the proper
bulletin to the caller (e.g. BTESTC. would be the COLOR version of bulletin
TEST). See section 6.3 for details.
RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-30
The bulletin menu defined in CONFIG parameter 61 should contain a list of
available bulletins. The .MNU extension activates RBBS-PC's sub-menu
feature (see section 7.7).
If only numbered bulletins are used, RBBS-PC will be able to scan for new
bulletins automatically (as long as parameter 62 has the proper setting).
For named bulletins, you must create a list of bulletins for RBBS-PC to
scan. The list should be in the file <prefix>.FCK in the same directory as
all the bulletins. The <prefix> is what is specified in parameter 63. In
our example, this file would be called B.FCK. Each bulletin should be
listed, without the prefix, one per line. Ex:
TEST
1
2
RBBS-PC
would check the date of the files BTEST, B1, B2 and BRBBS-PC. Note that B1
and B2 are considered Numbered bulletins, but if B.FCK is used, ALL
bulletins are considered Named bulletins.
News Bulletin File
------------------
The NEWS file is a special bulletin that is automatically displayed to a
caller at login if it has been updated since his last call. The NEWS
bulletin is NOT located with the general bulletin files. It should be
placed in the same directory as the WELCOME file. The name of the NEWS
file is <conference>.NWS. The <conference> is the name of the RBBS-PC
conference to which the news belongs (each conference can have a separate
news file). The MAIN news file, shown to callers at login, is named
MAIN.NWS. News files can support color and graphics (see section 6.3).